<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>getopts</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_871">&nbsp;</a>NAME</h4><blockquote>
getopts - parse utility options
</blockquote><h4><a name = "tag_001_014_872">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

getopts <i>optstring name </i><b>[</b><i>arg</i>...<b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_873">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>getopts</i>
utility can be used to retrieve options and option-arguments
from a list of parameters.
It supports the utility argument syntax
guidelines 3 to 10, inclusive, described in
the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> .
<p>
Each time it is invoked, the
<i>getopts</i>
utility places the value of the
next option in the shell variable
specified by the
<i>name</i>
operand and the
index of the next argument to be processed in the shell variable
<i>OPTIND .
</i>Whenever the shell is invoked,
<i>OPTIND</i>
will be initialised to 1.
<p>
When the option requires an option-argument, the
<i>getopts</i>
utility will place it in the shell variable
<i>OPTARG .
</i>If no option was found, or if the
option that was found does not have an option-argument,
<i>OPTARG</i>
will be unset.
<p>
If an option character not contained in the
<i>optstring</i>
operand is found
where an option character is expected, the shell variable specified by
<i>name</i>
will be set to the question-mark
(?)
character.
In this case, if
the first character in
<i>optstring</i>
is a colon
(:),
the shell variable
<i>OPTARG</i>
will be set to the option character found,
but no output will be written to standard error;
otherwise, the shell variable
<i>OPTARG</i>
will be unset and a diagnostic message will be
written to standard error.
This condition is considered to be an
error detected in the way arguments were presented to the invoking application,
but is not an error in
<i>getopts</i>
processing.
<p>
If an option-argument is missing:
<ul>
<p>
<li>
If the first character of
<i>optstring</i>
is a colon, the shell variable
specified by
<i>name</i>
will be set to the colon character and the shell variable
<i>OPTARG</i>
will be set to the option character found.
<p>
<p>
<li>
Otherwise, the shell variable specified by
<i>name</i>
will be set to the
question-mark character, the shell variable
<i>OPTARG</i>
will be unset,
and a diagnostic message will be written to standard error.
This condition is considered to be an error detected in the
way arguments were presented to the invoking application, but
is not an error in
<i>getopts</i>
processing; a diagnostic message
will be written as stated, but the exit status will be zero.
<p>
</ul>
<p>
When the end of options is encountered, the
<i>getopts</i>
utility will exit
with a return value
greater than zero; the shell variable
<i>OPTIND</i>
will be set to the
index of the first non-option-argument,
where the first
--
argument is considered to be an option-argument if there are no other
non-option-arguments appearing before it,
or the value
$#
+ 1 if there are no
non-option-arguments; the
<i>name</i>
variable will be set to the question-mark
character.
Any of the following
identifies the end of options:
the special option
--,
finding an argument that does not
begin with a "-", or encountering an error.
<p>
The shell variables
<i>OPTIND</i>
and
<i>OPTARG</i>
are local to the caller of
<i>getopts</i>
and are not exported by default.
<p>
The shell variable specified by the
<i>name</i>
operand,
<i>OPTIND</i>
and
<i>OPTARG</i>
affect the current shell execution environment; see
<xref href=shexenv><a href="chap2.html#tag_001_012">
Shell Execution Environment
</a></xref>.
<p>
If the application sets
<i>OPTIND</i>
to the value 1, a new set of parameters can be used:
either the current positional parameters or new
<i>arg</i>
values.
Any other attempt to invoke
<i>getopts</i>
multiple times in a single shell execution environment with
parameters (positional parameters or
<i>arg</i>
operands) that are not the same in all invocations, or with an
<i>OPTIND</i>
value modified to be a value other than 1, produces unspecified results.
</blockquote><h4><a name = "tag_001_014_874">&nbsp;</a>OPTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_875">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>optstring</i><dd>
A string containing the option characters
recognised by the utility invoking
<i>getopts</i>.
If a character is followed
by a colon, the option will be expected to have an
argument, which should be supplied as a separate argument.
Applications should specify
an option character and its option-argument as separate arguments,
but
<i>getopts</i>
will interpret the characters following an option
character requiring arguments as an argument whether or not
this is done.
An explicit null option-argument
need not be recognised if it is not supplied as a
separate argument when
<i>getopts</i>
is invoked.
(See also the <b>XSH</b> specification
<i><a href="../xsh/getopt.html">getopt()</a></i>
function.)
The characters question-mark and colon
must not be used as option characters by an application.
The use of other option characters that are not alphanumeric
produces unspecified results.
If the option-argument is not
supplied as a separate argument
from the option character, the value in
<i>OPTARG</i>
will be stripped of the option character and the "-".
The first character in
<i>optstring</i>
will determine how
<i>getopts</i>
will behave if an option character is not known
or an option-argument is missing.


<dt><i>name</i><dd>The name of a shell variable that will be set by the
<i>getopts</i>
utility to the option character that was found.

</dl>
<p>
The
<i>getopts</i>
utility by default will parse positional parameters passed
to the invoking shell procedure.
If
<i>arg</i>s
are given, they will be parsed instead of the positional parameters.
</blockquote><h4><a name = "tag_001_014_876">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_877">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_878">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>getopts</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments and input files).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
<dt><i>OPTIND</i><dd>
This variable will be used by the
<i>getopts</i>
utility as the index of the next argument to be processed.

</dl>
</blockquote><h4><a name = "tag_001_014_879">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_880">&nbsp;</a>STDOUT</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_881">&nbsp;</a>STDERR</h4><blockquote>
Whenever an error is detected
and the first character in the
<i>optstring</i>
operand is not a colon
(:),
a diagnostic message will be written to
standard error
with the following information in an unspecified format:
<ul>
<p>
<li>
The invoking program name will be identified in the message.
The invoking program
name will be the value of the shell special parameter
0
(see
<xref href=specpar><a href="chap2.html#tag_001_005_002">
Special Parameters
</a></xref>)
at the time the
<i>getopts</i>
utility is invoked.
A name equivalent to:
<pre>
<code>
basename "$0"
</code>
</pre>
may be used.
<p>
<li>
If an option is found that was not specified in
<i>optstring,</i>
this error will be identified and the invalid
option character will be identified in the message.
<p>
<li>
If an option requiring an option-argument is found, but an option-argument
is not found,
this error will be identified and the invalid
option character will be identified in the message.
<p>
</ul>
</blockquote><h4><a name = "tag_001_014_882">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_883">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_884">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>An option, specified or unspecified by
<i>optstring</i>,
was found.

<dt>&gt;0<dd>The end of options was encountered or an error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_885">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_886">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
Since
<i>getopts</i>
affects the current shell execution environment,
it is generally provided as a shell regular built-in.
If it is called in a subshell or separate utility execution environment,
such as one of the following:
<pre>
<code>
(getopts abc value "$@")
nohup getopts ...
find . -exec getopts ... \;
</code>
</pre>
it will not affect the shell variables in the caller's environment.
<p>
Note that shell functions share
<i>OPTIND</i>
with the calling shell even though
the positional parameters are changed.
Functions that want to use
<i>getopts</i>
to parse their arguments will usually want to save the value of
<i>OPTIND</i>
on entry and restore it before returning.
However, there will be
cases when a function will want to change
<i>OPTIND</i>
for the calling shell.
</blockquote><h4><a name = "tag_001_014_887">&nbsp;</a>EXAMPLES</h4><blockquote>
The following example script parses and displays its arguments:
<pre>
<code>
aflag=
bflag=
while getopts ab: name
do
    case $name in
    a)    aflag=1;;
    b)    bflag=1
          bval="$OPTARG";;
    )   printf "Usage: %s: [-a] [-b value] args\n" $0
          exit 2;;
    esac
done
if [ ! -z "$aflag" ]; then
    printf "Option -a specified\n"
fi
if [ ! -z "$bflag" ]; then
    printf 'Option -b "%s" specified\n' "$bval"
fi
shift $(($OPTIND - 1))
printf "Remaining arguments are: %s\n" "$*"
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_888">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_889">&nbsp;</a>SEE ALSO</h4><blockquote>
The <b>XSH</b> specification description of
<i><a href="../xsh/getopt.html">getopt()</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
